Storybook for React — Naming and Hierarchy

Storybook lets us prototype components easily with various parameters.

In this article, we’ll look at how to name stories with Storybook.

Naming Components and Hierarchy

The title property is in the object we export as a default export in the story.

For example, we have:

src/stories/Button.stories.js

import React from 'react';

import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Button',
};

export const Large = Template.bind({});
Large.args = {
  size: 'large',
  label: 'Button',
};

export const Small = Template.bind({});
Small.args = {
  size: 'small',
  label: 'Button',
};

The title is at the object at the top.

We put them into the Example group with Example/ .

A forward slash separates the group into a tree of groups.

This will be displayed as a treeview on the left side of the Storybook screen so we can expand and collapse the groups.

Roots

The default group is the root group if we don’t have any group name specified.

Sorting Stories

We can sort stories by adding the storySort method the parameters object we export in the .storybook/preview.js :

import React from 'react';

export const parameters = {
  options: {
    storySort: (a, b) => a[0].localeCompare(b[0])
  },
};

We added the storySort method to our app with a comparator function to sort the stories alphabetically.

a[0] has the ID string of the story.

The storySort property can also accept an object literal:

.storybook/preview.js

import React from 'react';

export const parameters = {
  options: {
    storySort: {
      method: 'alphabetical',
      order: [],
      locales: 'en-US',
    }
  },
};

method is a string that tells Storybook how to sort the stories.

order is an array of story names that we can display in the order they appear in the array.

locales is a string with the locale used for sorting.

The order array can be nested to sort story groups.

For example, we can write:

import React from 'react';

export const parameters = {
  options: {
    storySort: {
      order: ['Introduction', 'Button'],
    }
  },
};

to sort the stories in the order they’re listed.

Document Components

We can document our components in various ways.

In the stories file, we export an object as the default export with the title and component properties.

The title is what we display on the screen.

And component is the component we’re previewing.

The props are automatically extracted from the component so that we can set them to our own values.

Subcomponents Parameter

We can document multiple components together.

For example, we can write:

src/stories/ButtonGroup.js

import React from 'react';

export const ButtonGroup = ({ children }) => {
  return <div>{children}</div>
}

src/stories/ButtonGroup.stories.js

import React from 'react';
import { Button } from './Button';
import { ButtonGroup } from './ButtonGroup';

export default {
  title: 'Example/ButtonGroup',
  component: ButtonGroup,
  subcomponents: { Button },
};

const Template = (args) => <ButtonGroup {...args} />;

export const Primary = Template.bind({});

We have the ButtonGroup component with a story.

The story file’s default export has the subcomponents property with the properties that are the child components of the ButtonGroup component.

Conclusion

We can document our components by naming them with Storybook.